Endereços e testes

Onde ficam a API, o painel e os downloads, e como testar a sua integração com segurança.

Endereços#

Todos usam HTTPS. A API não aceita chamadas de navegadores (não há CORS): ela é chamada pelo seu servidor.

Testar a sua integração#

Há um único ambiente, o de produção, e as assinaturas feitas nele são reais: usam o carimbo de tempo da autoridade credenciada e contam na cota do seu plano. Para testar com segurança:

1. Crie uma chave de API só para testes (por exemplo, homologacao) e revogue-a quando terminar. A chave de produção não precisa existir enquanto você testa.
2. Use PDFs de teste, nunca documentos de clientes.
3. Teste com o seu próprio certificado ou com um certificado de teste emitido para você.
4. Use uma PKI privada para os certificados de teste. Cadastre uma AC de teste sua como contexto privado (PUT /v1/private-security-contexts/{slug}, ou pelo painel) e assine com securityContextId=private:<identificador> e a política pades-basic. Os certificados dessa AC não valem na ICP-Brasil, e é por isso que servem para teste. Veja Políticas e contextos.
5. Provoque os erros de propósito: um certificado vencido, uma chave de API revogada, um PDF acima do limite. Confira que a sua tela trata cada código de erro.

Lista de verificação para ir à produção#

• [ ] A chave de API está num cofre de segredos ou variável de ambiente, fora do repositório e fora do navegador.
• [ ] O seu servidor chama DELETE /v1/pades-signatures/{token} ao terminar, inclusive nos caminhos de erro.
• [ ] O complete usa Idempotency-Key e repete em falha de rede (o cliente PHP e o SDK JavaScript já fazem). Veja Sessões.
• [ ] Você trata 429 esperando o Retry-After, e 409 complete_in_progress repetindo com a mesma chave.
• [ ] O seu site é servido em HTTPS (a extensão só atua em HTTPS) e leva o usuário à página de instalação quando não detecta a extensão.
• [ ] Você registra o X-Request-Id de cada erro.
• [ ] Os limites do PHP e do servidor web comportam o maior lote (veja Assinar PDFs no seu sistema).
• [ ] A sua tela mostra o reason das recusas de certificado em linguagem do usuário (Identidade do certificado).