Primeira integração

Do zero até a primeira página de vendas, com curl. Antes, faça os cadastros e avise o cliente de que ele vai receber o pedido.

1. Pegue o token de acesso

curl -X POST "$BASE_URL/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials"}'

{
  "message": "Token emitido",
  "result": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 600
  },
  "error": null
}

Guarde data.access_token. Ele vale 10 minutos. Use o mesmo token em todas as chamadas desse período.

export ACCESS_TOKEN="eyJhbGciOiJIUzI1NiIs..."

2. Peça acesso ao cliente

curl -X POST "$BASE_URL/v1/access-requests" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cnpj":"12.345.678/0001-95"}'

{
  "message": "Pedido recebido",
  "result": true,
  "data": { "status": "RECEIVED" },
  "error": null
}

3. O cliente aprova no painel

Peça ao cliente para entrar no painel do Concilia+ e aprovar o pedido da sua software house. Enquanto ele não aprova, a consulta responde PENDING.

4. Busque o token do cliente

curl "$BASE_URL/v1/access-requests/12345678000195" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Depois da aprovação, a primeira consulta traz o company_token:

{
  "message": "Situação do pedido",
  "result": true,
  "data": {
    "status": "APPROVED",
    "requested_at": "2026-10-21T13:02:11.000Z",
    "company_token": "cpt_q1w2e3r4t5y6u7i8o9p0a1s2d3f4g5h6j7k8l9z0x1c"
  },
  "error": null
}

Salve o company_token junto do CNPJ. As consultas seguintes devolvem APPROVED sem o token.

export COMPANY_TOKEN="cpt_q1w2e3r4t5y6u7i8o9p0a1s2d3f4g5h6j7k8l9z0x1c"

5. Leia as vendas

curl "$BASE_URL/v1/sales?updated_since=2026-10-01T00:00:00Z&page=1&page_size=500" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Company-Token: $COMPANY_TOKEN"

{
  "message": "Vendas",
  "result": true,
  "data": {
    "items": [
      {
        "id": "84213",
        "acquirer": "REDE",
        "merchant_code": "12345678",
        "nsu": "000123456",
        "sale_date": "2026-10-01",
        "status": "APPROVED",
        "gross_amount": "150.000000",
        "net_amount": "146.250000",
        "updated_at": "2026-10-02T06:15:03.482915Z"
      }
    ],
    "page": 1,
    "page_size": 500,
    "has_more": true,
    "next_updated_since": "2026-10-21T15:42:10.000Z"
  },
  "error": null
}

O item acima está resumido. Todos os campos estão em GET /v1/sales.

6. Siga as páginas

Enquanto has_more for true, peça a página seguinte, com o mesmo updated_since:

curl "$BASE_URL/v1/sales?updated_since=2026-10-01T00:00:00Z&page=2&page_size=500" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Company-Token: $COMPANY_TOKEN"

7. Guarde a data para a próxima vez

Guarde o next_updated_since da página 1. Na próxima sincronização, use-o como updated_since, e virão só as vendas criadas ou alteradas desde então. É a única coisa que o seu sistema precisa guardar entre uma sincronização e outra.

O ciclo completo (quando repetir, como deduplicar, como tratar erros) está em Sincronização incremental.