Pular para o conteúdo principal

Ambientes e autenticação

Esta seção explica os ambientes disponíveis na Auco e como se autenticar de forma segura ao consumir a API.

Versionamento da API​

Todas as requisições devem incluir a versão atual da API na URL base. Atualmente usamos a versão v1.5, com o sufixo /ext indicando os endpoints destinados a integrações externas.

Ambientes disponíveis​

A Auco oferece dois ambientes separados:

🔧 Ambiente de testes (stage)​

  • URL base: https://dev.auco.ai/v1.5/ext
  • Destinado a integrações, testes e desenvolvimento.
  • Não gera cobranças reais nem movimentações reais de documentos.
  • Você pode solicitar acesso criando uma conta em stage.auco.ai.

🚀 Ambiente de produção​

  • URL base: https://api.auco.ai/v1.5/ext
  • Este ambiente executa fluxos documentais reais e contabiliza os documentos assinados ou entregues.
  • Exige um pacote de créditos ativo e uma conta de produção devidamente configurada.

Autenticação​

A API da Auco usa dois tipos de chaves de autenticação: pública e privada. Essas chaves devem ser incluídas nos cabeçalhos da requisição conforme o tipo de operação:

  • Leitura (GET): use a chave pública (puk_...)
  • Escrita (POST, PUT, DELETE): use a chave privada (prk_...)

🔑 Cabeçalho obrigatório​

Authorization: YOUR_PUBLIC_OR_PRIVATE_KEY

📘 Exemplo curl para leitura (GET)​

curl -X GET https://dev.auco.ai/v1.5/ext/document \
  -H "Authorization: puk_ocG0ODMlBlAN4NOi4GxVJjmC7Examaple" \
  -H "Content-Type: application/json"

📘 Exemplo curl para escrita (POST)​

curl -X POST https://dev.auco.ai/v1.5/ext/document/save \
  -H "Authorization: prk_ocG0ODMlBlAN4NOi4GxVJjmC7Examaple" \
  -H "Content-Type: application/json" \
  -d '{ "name": "document.pdf" }'

Nota: mantenha suas chaves privadas em segurança. Nunca as compartilhe publicamente nem as inclua em clientes públicos, como navegadores.

Recomendações​

  • Use o ambiente stage para todos os testes iniciais antes de migrar para produção.
  • Certifique-se de usar a chave pública para GET e a chave privada para POST, PUT e DELETE.
  • Atualize tanto a URL base quanto as chaves ao migrar para produção.
  • Proteja suas chaves privadas: nunca as compartilhe publicamente nem as inclua em clientes públicos, como navegadores ou aplicativos móveis.
  • Se você automatiza processos, considere implementar a rotação periódica das chaves.

Código de erro comum​

  • 401 Unauthorized: não foi incluída uma chave válida no cabeçalho Authorization, ou foi usado o tipo de chave errado para a operação (leitura/escrita).