Autenticação
Como criar, usar, trocar e proteger as chaves de API da CartaFlow.
Toda requisição à API leva uma chave de API no cabeçalho Authorization. A chave identifica a sua conta: tudo o que você cria com ela pertence à conta e é cobrado do saldo dela.
A chave
Toda chave começa com cf_live_ e usa a URL https://api.cartaflow.com.br/v1. Com ela, as correspondências e as verificações são impressas, postadas e cobradas do saldo da conta. Para conferir um envio sem custo, use POST /v1/letters/quote: ele valida tudo e devolve o preço, sem criar nem cobrar nada.
As chaves só existem depois que a CartaFlow aprova o cadastro da empresa.
Criar uma chave
- No painel da CartaFlow, abra Desenvolvedores > Chaves de API.
- Dê um nome que diga onde a chave vai ser usada, como "ERP financeiro".
- Copie a chave. Ela aparece uma vez só: depois disso, o painel mostra só o começo e o fim dela.
- Guarde a chave em uma variável de ambiente ou em um cofre de segredos do seu servidor.
Você pode ter várias chaves ativas ao mesmo tempo, por exemplo uma para cada sistema que integra com a CartaFlow. Isso também permite trocar uma chave sem parar a integração.
Usar a chave
Envie a chave no cabeçalho Authorization, depois da palavra Bearer:
curl https://api.cartaflow.com.br/v1/balance \
-H "Authorization: Bearer $CARTAFLOW_API_KEY"Para saber a qual conta uma chave pertence, chame GET /v1/account. Isso é útil em integrações que atendem vários clientes, como um ERP: cada cliente cadastra a própria chave, e o seu sistema confirma de quem ela é.
A chave fica só no servidor
A chave dá acesso ao seu saldo e aos dados dos seus destinatários. Por isso:
- Chame a API só a partir do seu servidor. A API não aceita requisições feitas pelo navegador (não libera CORS), então uma chave colocada no código de um site nem funciona.
- Nunca coloque a chave em um aplicativo de celular, em código que roda no navegador, no repositório ou em logs.
- Se o seu aplicativo precisa criar correspondências, ele chama o seu servidor, e o seu servidor chama a CartaFlow.
Uma chave vazou
Revogue a chave na hora, no painel, em Desenvolvedores > Chaves de API. A revogação vale imediatamente: qualquer requisição com a chave revogada recebe 401. Depois, crie uma chave nova e atualize o seu servidor.
Trocar uma chave
Para trocar uma chave sem interromper os envios:
- Crie uma chave nova no painel.
- Atualize a variável de ambiente do seu servidor e publique a mudança.
- Confira que as chamadas funcionam com a chave nova.
- Revogue a chave antiga no painel.
Erros de autenticação
| HTTP | error.code | O que aconteceu | Como resolver |
|---|---|---|---|
| 401 | api_key_missing | A requisição não tem o cabeçalho Authorization. | Envie Authorization: Bearer seguido da sua chave de API. |
| 401 | api_key_invalid | A chave não existe ou está escrita de forma errada. | Copie a chave de novo no painel. Ela começa com cf_live_. |
| 401 | api_key_revoked | A chave foi revogada no painel. | Crie uma chave nova e atualize a variável de ambiente do seu sistema. |
| 403 | account_suspended | A conta está suspensa e não pode criar envios. | Fale com o suporte da CartaFlow pelo painel. |
O formato de todas as respostas de erro está em Erros.