Partner API

O Partner API destina-se a bancos, bots, painéis de revendedores, sistemas de provisionamento interno e outras integrações confiáveis ​​entre servidores. A versão 10.5.0 é o primeiro contrato de máquina pronto para o Banco.

URL base

https://p-api.model-gate.com

Autenticação

Authorization: Bearer mg_partner_...

Cada resposta é JSON, incluindo 404, 405, 429, e 500, e inclui X-Request-ID. Uso de respostas Cache-Control: no-store; o host parceiro não usa sessões PHP do navegador. Todos os carimbos de data/hora externos são UTC RFC3339 (YYYY-MM-DDTHH:MM:SSZ).

Todos POST, PATCH, e DELETE operações exigem um único Idempotency-Key cabeçalho. O Model Gate mantém o resultado criptografado por 7 dias, portanto, uma nova tentativa da mesma solicitação retorna o resultado original sem realizar a mutação novamente. Reutilizar a mesma chave para um método/caminho/corpo diferente retorna HTTP 409.

As solicitações de parceiros são protegidas por um limite de taxa por minuto no nível da conta configurado por PARTNER_API_RATE_LIMIT_PER_MINUTE (padrão 600). As respostas incluem X-RateLimit-Limit, X-RateLimit-Remaining, e X-RateLimit-Reset; HTTP 429 também inclui Retry-After.

Crie ou gere novamente a chave Partner API no perfil Model Gate. O token de portador completo é mostrado apenas uma vez na geração/rotação e o Model Gate armazena apenas seu hash SHA-256 mais um prefixo de exibição. Salve o token imediatamente em seu gerenciador de segredos do lado do servidor; se estiver perdido, gire-o.

O perfil tem um separado Lista de permissões de IP da API. Quando não estiver vazio, Partner API solicitações deverão ser originadas de um endereço IPv4/IPv6 exato ou prefixo CIDR permitido. As regras da API da organização empresarial se aplicam além da regra pessoal. Uma fonte rejeitada por uma das listas de permissões efetivas recebe HTTP 403 com error.type = ip_not_allowed.

Para contas empresariais, a credencial Partner API está disponível apenas para o proprietário verificado da organização. Os principais funcionários e a atribuição de credenciais comerciais delegadas são gerenciados no painel da web, onde as permissões de execução do grupo podem ser validadas. Portanto, as chaves comerciais criadas pelo parceiro usam o proprietário como proprietário da cobrança e principal da credencial. Um fornecido group_id deve nomear um grupo ativo pertencente à conta; um grupo desconhecido/congelado é rejeitado com HTTP 422 em vez de criar silenciosamente uma chave desagrupada.

Valores decimais

Os campos financeiros e de uso são sempre strings JSON:

{
  "spend_limit": "100.0000000000",
  "usage": "12.3456789000",
  "remaining": "87.6543211000",
  "usage_price_multiplier": "0.900000"
}

Use aritmética decimal de precisão arbitrária. Nunca converta esses valores para float.

Capacidades

• Crie, liste, atualize, gire, congele, descongele e exclua chaves de API.
• Configure a avaliação de uso por chave.
• Crie e gerencie grupos.
• Mova chaves entre grupos.
• Leia o uso da chave e do grupo.
• Leia o histórico de solicitações finalizadas para uma chave no pedido de tempo de término com páginas de 1 a 100 linhas e detalhamento de token/preço. O histórico detalhado de solicitações é retido a quente para API_REQUESTS_HOT_RETENTION_DAYS (padrão 7 dias); a reconciliação financeira de longo prazo usa o diário de transações de saldo.
• Leia o saldo da conta corrente e as transações do saldo da conta com paginação do cursor.
• Leia eventos de auditoria de gerenciamento de parceiros com paginação de cursor.
• Pesquise resultados de inferência assíncrona.

Ver todos os Partner API pontos de extremidade para obter exemplos completos de solicitação e resposta.

Os registros recentes do histórico de solicitações incluem principal_user_id quando o principal da credencial ainda existir, separadamente do proprietário do faturamento da empresa.

Contrato legível por máquina

O contrato OpenAPI 3.1 é enviado com cada versão como resources/contracts/partner-api.openapi.yaml. Trate-o junto com estas Partner API páginas como o contrato de integração do Banco. Campos JSON desconhecidos e parâmetros de consulta desconhecidos são rejeitados em vez de ignorados silenciosamente.