Primeiros passos
Crie a integração no Afflux, gere a chave e faça a primeira chamada à API.
Em resumo
- Alguém da sua empresa com acesso de administração cria a integração e gera a chave no Afflux.
- A chave é mostrada uma única vez: guarde-a num cofre de segredos, nunca no código.
- A primeira chamada é
GET /integracao: ela confirma a chave, a organização e as permissões. - Para testar sem dados reais, peça à equipe do Afflux uma organização de demonstração.
Crie a integração
No Afflux, em ConfiguraçõesIntegraçõesAPI do Afflux, clique em Nova integração. Dê um nome que identifique o sistema (por exemplo, "ERP Protheus — financeiro") e marque só o que ele precisa ler. O passo a passo para quem administra está em Integração por API.
Gere a chave
Na tela da integração, clique em Gerar chave. A chave começa com afx_live_ e aparece uma vez só. Copie e entregue a quem mantém o sistema por um canal seguro.
Confira a chave
curl https://app.afflux.com.br/api/v1/integracao \
-H "Authorization: Bearer $AFFLUX_CHAVE"A resposta traz a integração, a organização e as permissões:
{
"integracao": { "id": "45fc7e5d-…", "nome": "ERP Protheus — financeiro" },
"organizacao": { "id": "f098574d-…", "razaoSocial": "Acme Serviços LTDA", "status": "ativa" },
"permissoes": ["contrato.ler", "faturamento.ler", "financeiro.ler", "fornecedor.ler"],
"limites": {
"porMinuto": { "maximo": 60, "restante": 59 },
"porDia": { "maximo": 10000, "restante": 9999, "renovaEm": "2026-10-10T03:00:00+00:00" }
},
"liberacaoPilotoAte": null
}Faça a carga inicial
Liste cada recurso do começo ao fim, seguindo o proximoCursor:
curl "https://app.afflux.com.br/api/v1/fornecedores?limite=100" \
-H "Authorization: Bearer $AFFLUX_CHAVE"Grave cada item pelo id (insere se é novo, atualiza se já existe) e guarde o proximoCursor da última página. Ele é o ponto de partida da próxima sincronização — veja Sincronização incremental.
Boas práticas desde o primeiro dia
- Uma integração por sistema. Se o ERP e uma ferramenta de BI leem o Afflux, crie duas integrações, cada uma com as suas permissões e a sua chave.
- Chave fora do código. Variável de ambiente ou cofre de segredos. Se ela vazar, revogue na hora e gere outra.
- Upsert por
id. Os ids do Afflux não mudam. Ocodigodo fornecedor e onumerodo contrato servem para casar com o cadastro que o ERP já tem. - Tolere o desconhecido. Campos novos e valores novos de situação podem aparecer sem mudar a versão. Ignore campo que não conhece; trate situação desconhecida como "outra".
- Respeite os limites. Em
429, espere oRetry-After. Consultar a cada 5 a 15 minutos é suficiente para a maioria dos casos.