Documentação OpenAPI: Método de Assinatura

Documentação OpenAPI: Descrição do Método de Assinatura

1. Visão Geral

Este documento descreve como os clientes usam criptografia assimétrica (RSA) para assinar solicitações de API e incluir a assinatura, ID do usuário e timestamp nos cabeçalhos da solicitação ao enviar para o servidor.

2. Descrição do Processo

2.1 Geração de Chaves

Os usuários geram pares de chaves públicas e privadas RSA.

Carregam a chave pública no backend do agente, enquanto a chave privada é armazenada com segurança pelo cliente.

2.2 Assinatura da Solicitação (Lado do Cliente)

O cliente gera um timestamp do tempo atual (timestamp Unix, preciso até segundos).

Comprime e ordena o corpo da solicitação de acordo com as regras JSON.

Concatena o timestamp e o corpo da solicitação em uma string, e a assina usando a chave privada.

Inclui a assinatura, ID do usuário e timestamp nos cabeçalhos da solicitação.

2.3 Envio da Solicitação

O cliente envia a solicitação assinada para o servidor, com os seguintes campos nos cabeçalhos da solicitação:

X-User-ID: ID do usuário.

X-Signature: Assinatura gerada usando a chave privada (codificada em Base64).

X-Timestamp: Timestamp.

3. Regras de Compressão e Ordenação JSON

Para garantir consistência entre cliente e servidor ao gerar e verificar assinaturas, o corpo da solicitação deve ser convertido em string JSON de acordo com as seguintes regras:

Stringificação JSON:

Use json.dumps() para converter todo o corpo da solicitação em uma string JSON.

Tipos de Dados:

Números não devem ser aspados.

Exemplo

Corpo da Solicitação Original

{
    "key2": "value2",
    "key1": "value1",
    "key3": {
        "nestedKey2": "nestedValue2",
        "nestedKey1": "nestedValue1"
    }
}

Corpo da Solicitação Formatado

{"key1":"value1","key2":"value2","key3":{"nestedKey1":"nestedValue1","nestedKey2":"nestedValue2"}}

4. Exemplo de Solicitação

Cabeçalhos da Solicitação

Corpo da Solicitação

{
    "key1": "value1",
    "key2": "value2"
}

5. Exemplos de Código

5.1 Gerar Assinatura (Lado do Cliente)

5.2 Enviar Solicitação (Lado do Cliente)

6. Notas Importantes

Segurança de Chaves: Chaves privadas devem ser armazenadas com segurança para prevenir vazamentos.

Sincronização de Tempo: Certifique-se de que o tempo do sistema cliente esteja sincronizado com o servidor para evitar falhas de verificação devido a diferenças de fuso horário.

HTTPS: Use protocolo HTTPS para transmissão de dados para garantir a segurança dos dados durante a transmissão.

Através das instruções e exemplos de código acima, os clientes podem gerar assinaturas corretamente e enviar solicitações, garantindo a integridade e segurança das solicitações de API.

7. Descrição do Método de Assinatura Webhook

7.1 Visão Geral

Este documento descreve como o servidor assina solicitações de callback webhook e como os agentes podem verificar assinaturas.

7.2 Gerenciamento de Chaves

O servidor usa algoritmo RSA para gerar pares de chaves públicas e privadas

Fornece a chave pública aos agentes, que configuram a chave pública em seu backend

O servidor mantém a chave privada segura para assinar solicitações webhook

7.3 Processo de Assinatura

O servidor gera um timestamp do tempo atual (timestamp Unix, preciso até segundos)

Converte o corpo da solicitação em uma string JSON

Concatena o timestamp e o corpo da solicitação em uma string, e a assina usando a chave privada

Inclui a assinatura e timestamp nos cabeçalhos da solicitação

7.4 Cabeçalhos da Solicitação

Quando o servidor envia solicitações webhook, os cabeçalhos da solicitação contêm os seguintes campos:

X-Signature: Assinatura gerada usando a chave privada (codificada em Base64)

X-Timestamp: Timestamp

7.5 Exemplo de Verificação de Assinatura (Lado do Agente)

7.6 Notas Importantes

Considerações do lado do agente:

Validação de Tempo: É recomendado verificar se o timestamp está dentro de um intervalo de tempo razoável (ex: 5 minutos) para prevenir ataques de replay

Segurança da Chave Pública: Embora chaves públicas possam ser disponibilizadas publicamente, ainda é recomendado transmiti-las e armazená-las através de canais seguros

HTTPS: Callbacks webhook devem usar protocolo HTTPS para garantir segurança na transmissão

Notas de implementação do lado do servidor:
4. Mecanismo de Retry ✅:

Implementado mecanismo de retry inteligente para solicitações de callback webhook

Lidar com diferentes tipos de erro adequadamente:

Timeout de rede: Aguardar 30 segundos antes do retry

Erros de servidor (5xx): Aguardar 1 minuto antes do retry

Erros de cliente (4xx): Apenas retry para códigos de erro específicos

Máximo de 3 tentativas de retry

Cada retry registra informações detalhadas

Garante que a mensagem eventualmente chegue aos servidores dos agentes

8. Descrição da Situação OpenAPI

8.1 Códigos de Status de Erro

invalidBody: Corpo da requisição não conforme com as especificações

Unauthorized: Falha na verificação de assinatura

Not Found: Recurso não encontrado

insufficientBalance: Saldo insuficiente

Too Many Requests: Solicitações frequentes demais

verifySignFailed: Todas as comparações de secret falharam

accountNotExist: Conta/Agente não existe

notAgencyMerchant: Ao filtrar informações de comerciantes, o accountId não é um comerciante agência, ou o comerciante da currencyAccount não é um comerciante agência

tradeCurrencyAccountFoundErr: Falha na consulta do comerciante de moeda

dbNotMatch: Para correspondência exata de dados únicos, quando os dados da requisição estão conformes mas nenhum dado correspondente é encontrado

Documentação OpenAPI: Método de Assinatura

Documentação OpenAPI: Descrição do Método de Assinatura#

1. Visão Geral#

2. Descrição do Processo#

2.1 Geração de Chaves#

2.2 Assinatura da Solicitação (Lado do Cliente)#

2.3 Envio da Solicitação#

3. Regras de Compressão e Ordenação JSON#

Exemplo#

Corpo da Solicitação Original#

Corpo da Solicitação Formatado#

4. Exemplo de Solicitação#

Cabeçalhos da Solicitação#

Corpo da Solicitação#

5. Exemplos de Código#

5.1 Gerar Assinatura (Lado do Cliente)#

5.2 Enviar Solicitação (Lado do Cliente)#

6. Notas Importantes#

7. Descrição do Método de Assinatura Webhook#

7.1 Visão Geral#

7.2 Gerenciamento de Chaves#

7.3 Processo de Assinatura#

7.4 Cabeçalhos da Solicitação#

7.5 Exemplo de Verificação de Assinatura (Lado do Agente)#

7.6 Notas Importantes#

8. Descrição da Situação OpenAPI#

8.1 Códigos de Status de Erro#