Autenticação

A API usa duas credenciais, com papéis diferentes:

Credencial	Identifica	Como obter	Onde vai	Validade
Token de acesso (access_token)	A sua software house	POST /oauth/token com client_id e client_secret	Authorization: Bearer <token>	10 minutos
Token do cliente (company_token)	A autorização de um cliente para a sua software house	GET /v1/access-requests/{cnpj}, depois da aprovação	X-Company-Token: <token>	Até ser revogado

Quais rotas pedem o quê

Rota	Authorization: Bearer	X-Company-Token
POST /oauth/token	Não (usa client_id e client_secret)	Não
POST /v1/access-requests	Sim	Não
GET /v1/access-requests/{cnpj}	Sim	Não
POST /v1/access-requests/{cnpj}/reissue	Sim	Não
GET /v1/sales	Sim	Sim
GET /v1/payments	Sim	Sim

O company_token só vale junto do token de acesso da mesma software house que fez o pedido. Os feeds não recebem CNPJ: o cliente é identificado pelo company_token.

Token de acesso

• É um JWT assinado pelo Concilia+. Trate-o como texto opaco e não dependa do conteúdo dele.
• Dura 600 segundos (expires_in). Peça um novo pouco antes de vencer ou quando receber 401.
• Cada software house pode emitir até 10 tokens por hora. Use o mesmo token em todas as chamadas, de todos os clientes, enquanto ele valer. Pedir um token por chamada estoura essa cota.
• Ele deixa de valer antes do prazo se o Concilia+ trocar o seu client_secret, revogar a software house ou se o seu acesso vencer.

Token do cliente

• Formato: cpt_ seguido de 43 caracteres (letras, números, - e _).
• É entregue uma única vez. O Concilia+ guarda só o hash dele e não consegue mostrá-lo de novo.
• Para de valer se o cliente revogar o acesso, se o Concilia+ revogar o vínculo, se a empresa for desativada ou se você pedir uma reemissão.

Quando dá 401

Toda falha de autenticação tem a mesma resposta, de propósito, sem dizer qual parte falhou:

{
  "message": "Não autorizado",
  "result": false,
  "data": null,
  "error": "Não autorizado"
}

Diante de um 401 num feed, siga esta ordem:

1. Peça um token de acesso novo e repita a chamada uma vez.
2. Se continuar 401, o problema é o company_token. Consulte GET /v1/access-requests/{cnpj}:
   • APPROVED: o token guardado está errado ou foi substituído. Use a reemissão.
   • REVOKED: o cliente cortou o acesso. Pare de sincronizar esse CNPJ e fale com o cliente.
   • NOT_FOUND: a empresa foi desativada no Concilia+. Pare de sincronizar esse CNPJ e fale com o cliente.

:::warning Segurança das credenciais

• Nunca coloque client_secret, access_token ou company_token em URL, log ou mensagem de erro.
• Faça todas as chamadas por HTTPS, com TLS 1.2 ou mais recente. Se alguma credencial foi enviada por http://, considere-a vazada e peça uma nova.
• A API é servidor a servidor: não a chame do navegador nem de um app instalado no computador do cliente. :::