> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar assinatura
> Instancia o contrato recorrente de um cliente, a partir de um plano ou de itens avulsos.
`POST /subscriptions`
Faz parte do recurso [Assinaturas](/pt-BR/subscriptions) — o conceito, os dez estados e a máquina de
transições estão lá.
Cria a assinatura e coloca o motor de cobrança para funcionar. A partir daqui, quem emite fatura e
quem cobra é a Z2Pay, no ritmo da recorrência configurada.
**Informe exatamente um entre `customerId` e `customer`.** Enviar os dois, ou nenhum, responde
`400`. O `customer` inline cria o cadastro na hora ou reaproveita um existente, casando primeiro
pelo documento e depois pelo e-mail — é o atalho para quem ainda não tem o `cust_`.
**Informe `planId`, `items`, ou os dois.** Sem nenhum dos dois não há o que cobrar. Com os dois, os
itens recorrentes do plano entram e os de `items` se somam a eles.
Quando **todos** os itens são avulsos, `recurrence` e `currency` passam a ser obrigatórios: não há
preço de onde derivá-los.
## O estado inicial não se escolhe
Não existe campo `status` no corpo. O estado em que a assinatura nasce é decidido pela combinação
que você envia, avaliada nesta ordem:
| O que você envia | Nasce como |
| -------------------------------------------------------------------- | ----------------------- |
| `enrollmentItems` **+** `bootstrapPayment` (adesão já paga por fora) | `active` |
| `enrollmentItems` **sem** `bootstrapPayment` | `pending_enrollment` |
| `trialSpec` com `requiresPaymentMethod` e **sem** forma de pagamento | `incomplete`, com prazo |
| `trialSpec` nos demais casos | `trialing` |
| Nada disso, **com** `defaultPaymentMethodRef` | `active` |
| Nada disso, **sem** `defaultPaymentMethodRef` | `incomplete`, sem prazo |
**`trialing` vence a forma de pagamento.** Com `trialSpec`, a assinatura entra em teste mesmo com
o cartão já cadastrado — e a primeira fatura só nasce quando o teste acaba. Se você esperava
cobrança imediata, não envie `trialSpec`.
**`pending_enrollment` tem prazo; `incomplete` quase nunca.** A adesão precisa ser paga dentro da
janela da conta (7 dias por padrão) ou a assinatura é cancelada. Já a `incomplete` só expira
quando nasceu de um teste com `requiresPaymentMethod` — cerca de 23 horas. A `incomplete` comum
fica parada até alguém agir. Ver [Do `incomplete` ao `active`](/pt-BR/subscriptions).
## Formas de pagamento
Em `defaultPaymentMethodRef`, o `type` diz o meio e o resto diz qual:
* **cartão novo** — tokenize com o Tokenizer SDK e envie o `tok_` em `token`. O cartão é salvo na
carteira do cliente antes de virar o padrão;
* **cartão já salvo** — envie o `crd_` em `cardId`. Ele precisa pertencer ao cliente da assinatura,
senão responde `409`;
* **PIX ou boleto** — só o `type`, sem `token` nem `cardId`.
**Três combinações são recusadas com `409`:**
* `enrollmentItems` sem `defaultPaymentMethodRef` — a adesão precisa de como ser cobrada;
* `trialSpec` junto com `enrollmentItems` — são opostos: um adia a cobrança, o outro a antecipa;
* `bootstrapPayment` numa assinatura que não nasceria `active` — ele afirma que o ciclo 1 já foi
pago, o que é incompatível com teste ou com falta de forma de pagamento.
**`referenceCode` é o seu identificador do contrato.** Volta nas respostas e é filtrável por
correspondência exata na [listagem](/pt-BR/subscriptions/list). Não é único: a Z2Pay não recusa
dois contratos com o mesmo código.
**`upfront` emite tudo de uma vez.** Com `invoiceGenerationMode: "upfront"`, todas as `maxCycles`
faturas nascem na criação, cada uma com o seu vencimento — e `maxCycles` passa a ser obrigatório.
O padrão, `just_in_time`, emite uma fatura por ciclo, na virada.
## Exemplo
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/subscriptions \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: e6c9b2a4-1f3d-4a7b-9c2e-0d8f1a2b3c4d" \
-d '{
"customerId": "cust_eqjzf65crxsrywqdfptanl7yp",
"planId": "plan_lhutpqeq2ml3stia4vn90xars",
"referenceCode": "contrato-2026-0042",
"defaultPaymentMethodRef": {
"type": "card",
"cardId": "crd_d6bvtkpr7fd4jrb3tbpm8ohqi"
}
}'
```
```json Resposta 201 theme={null}
{
"id": "sub_x33m4yn6brazh71en4mki6f5c",
"number": { "sequence": 42 },
"referenceCode": "contrato-2026-0042",
"customerId": "cust_eqjzf65crxsrywqdfptanl7yp",
"status": "active",
"currency": "BRL",
"collectionMethod": "charge_automatically",
"collectionTiming": "prepaid",
"invoiceGenerationMode": "just_in_time",
"recurrence": {
"interval": 1,
"unit": "month",
"anchor": "subscription_start",
"collectionTiming": "prepaid"
},
"cancelAtPeriodEnd": false,
"maxCycles": null,
"currentPeriodStart": "2026-08-10T12:00:00.000Z",
"currentPeriodEnd": "2026-09-10T12:00:00.000Z",
"nextInvoiceAt": "2026-09-10T12:00:00.000Z",
"items": [
{
"id": "subi_wq3n8fk52hbdzr7m0aeypvcjt",
"subscriptionId": "sub_x33m4yn6brazh71en4mki6f5c",
"planItemId": "pli_oaimno59ai3uuqwq0ti7gxs0j",
"priceVersionId": "price_l1r8693wk6ksbd9044bwvwu93",
"name": "Assinatura Pro",
"unitAmount": 9900,
"quantity": 1
}
]
}
```
O exemplo está abreviado — o playground ao lado mostra o corpo inteiro.
## OpenAPI
````yaml openapi/billing.json POST /subscriptions
openapi: 3.0.3
info:
title: Z2Pay Billing API
version: 1.0.0
description: Cobrança recorrente da Z2Pay — planos, assinaturas e faturas
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Invoices
description: Faturas emitidas pelas assinaturas
- name: Plans
description: Planos de cobrança e versões de preço
- name: Subscriptions
description: Assinaturas recorrentes
paths:
/subscriptions:
post:
tags:
- Subscriptions
summary: Criar assinatura
description: >-
Cria uma nova assinatura. Informe **exatamente um**: `customerId`
(customer existente) OU `customer` (dados inline — criado/reaproveitado,
match por documento depois email); enviar os dois, ou nenhum, retorna
`400`. Forma de pagamento em `defaultPaymentMethodRef`: cartão novo via
`token` (`tok_` do Tokenizer SDK, salvo permanentemente) OU cartão salvo
via `cardId` (`crd_`); para PIX/boleto, só o `type`. `referenceCode`
opcional correlaciona o contrato com o sistema do integrador. O status
inicia como `active` quando há forma de pagamento, senão `incomplete`.
operationId: SubscriptionController_create
parameters:
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customerId:
type: string
minLength: 1
description: >-
ID de um cliente existente (exatamente um entre customerId e
customer).
customer:
type: object
properties:
name:
type: string
minLength: 2
description: Nome completo do cliente.
email:
type: string
format: email
description: E-mail do cliente.
type:
type: string
enum:
- individual
- company
description: >-
Tipo de cliente: individual (pessoa física) ou company
(pessoa jurídica).
document:
type: string
minLength: 6
description: Documento do cliente (CPF ou CNPJ, somente dígitos).
documentType:
type: string
enum:
- cpf
- cnpj
- passport
description: 'Tipo do documento do cliente: cpf ou cnpj.'
phone:
type: string
minLength: 1
description: >-
Telefone do cliente (formato E.164, ex.:
+5511987654321).
address:
type: object
properties:
street:
type: string
nullable: true
description: Logradouro (rua, avenida).
number:
type: string
nullable: true
description: Número do endereço.
complement:
type: string
nullable: true
description: Complemento do endereço (apartamento, bloco, sala).
neighborhood:
type: string
nullable: true
description: Bairro.
city:
type: string
nullable: true
description: Cidade.
state:
type: string
nullable: true
description: 'Estado ou UF (ex.: SP).'
postalCode:
type: string
nullable: true
description: CEP / código postal (somente dígitos).
country:
type: string
nullable: true
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
required:
- street
- number
- complement
- neighborhood
- city
- state
- postalCode
- country
required:
- name
- email
- type
- document
- phone
description: >-
Cliente inline: cria ou reusa (por documento, depois email)
na criação da assinatura.
planId:
type: string
minLength: 1
description: >-
Instancia a assinatura a partir de um plano; pode coexistir
com items extras.
itemOverrides:
type: object
additionalProperties:
type: integer
minimum: 0
exclusiveMinimum: true
description: >-
Override de quantidade por item do plano: {
"": quantity }.
items:
type: array
items:
oneOf:
- type: object
properties:
priceVersionId:
type: string
minLength: 1
description: >-
Versão de preço (Price) que dita unitAmount,
currency e recurrence.
quantity:
type: integer
minimum: 0
exclusiveMinimum: true
default: 1
description: Quantidade do item (default 1).
required:
- priceVersionId
- type: object
properties:
description:
type: string
minLength: 1
maxLength: 200
description: Descrição do item avulso (inline).
unitAmount:
type: integer
minimum: 0
exclusiveMinimum: true
description: Valor unitário por ciclo, em centavos.
quantity:
type: integer
minimum: 0
exclusiveMinimum: true
default: 1
description: Quantidade do item (default 1).
required:
- description
- unitAmount
default: []
description: >-
Items da assinatura: referência (priceVersionId) ou inline
(description + unitAmount em centavos).
recurrence:
type: object
properties:
interval:
type: integer
minimum: 0
exclusiveMinimum: true
unit:
type: string
enum:
- day
- week
- month
- year
anchor:
type: string
enum:
- subscription_start
- day_of_month
- end_of_month
anchorDay:
type: integer
minimum: 1
maximum: 31
collectionTiming:
type: string
enum:
- prepaid
- postpaid
default: prepaid
required:
- interval
- unit
- anchor
description: >-
Regra de recorrência; obrigatória quando todos os items são
inline.
currency:
type: string
description: >-
Moeda ISO 4217; obrigatória quando todos os items são
inline.
billingGroupId:
type: string
description: Grupo de cobrança (billing group).
defaultPaymentMethodRef:
type: object
properties:
type:
type: string
enum:
- card
- boleto
- pix
description: Tipo da forma de pagamento.
token:
type: string
nullable: true
description: >-
Cartão novo: token gerado pelo Tokenizer SDK (`tok_`).
Exclusivo com `cardId`.
cardId:
type: string
nullable: true
description: >-
Cartão já salvo do cliente (`crd_`), obtido em resposta
anterior. Exclusivo com `token`.
required:
- type
description: >-
Forma de pagamento default dos ciclos. Cartão: `token`
(novo, do Tokenizer SDK) OU `cardId` (cartão já salvo do
cliente).
splitConfig:
type: array
items:
type: object
properties:
recipientId:
type: string
minLength: 1
type:
type: string
enum:
- sale
- interest
- platform_fee
default: sale
value:
type: number
minimum: 0.01
valueType:
type: string
enum:
- percentage
- fixed
processingFee:
type: boolean
liable:
type: boolean
required:
- recipientId
- value
- valueType
minItems: 1
description: >-
Divisão de receita aplicada a cada ciclo cobrado; ausente =
100% pro recebedor owner.
collectionMethod:
type: string
enum:
- charge_automatically
default: charge_automatically
description: >-
Como a fatura é cobrada. Hoje só a cobrança automática na
forma de pagamento padrão.
collectionTiming:
type: string
enum:
- prepaid
- postpaid
default: prepaid
description: >-
'prepaid' (default) cobra no início do ciclo; 'postpaid'
cobra no fim.
invoiceGenerationMode:
type: string
enum:
- just_in_time
- upfront
default: just_in_time
description: >-
'just_in_time' (default) gera 1 invoice por ciclo; 'upfront'
emite todas na criação (requer maxCycles).
paymentBehavior:
type: string
enum:
- allow_incomplete
- error_if_incomplete
default: allow_incomplete
description: >-
O que fazer quando a primeira cobrança da assinatura não é
aprovada. `allow_incomplete` (default) cria a assinatura
mesmo assim, com a fatura em aberto e a régua de cobrança
seguindo. `error_if_incomplete` cancela a assinatura quando
a primeira cobrança falha — use quando não fizer sentido
manter um contrato que nunca chegou a ser pago.
enrollmentInstallments:
type: integer
minimum: 1
maximum: 12
description: >-
Parcelas no cartão da fatura de adesão (1–12; default 1); >1
exige defaultPaymentMethodRef.type=card.
enrollmentItems:
type: array
items:
type: object
properties:
description:
type: string
minLength: 1
description: Descrição do item de adesão.
amount:
type: integer
minimum: 0
exclusiveMinimum: true
description: Valor unitário do item de adesão, em centavos.
quantity:
type: integer
minimum: 0
exclusiveMinimum: true
description: Quantidade do item de adesão.
required:
- description
- amount
- quantity
description: >-
Itens de adesão cobrados uma única vez na 1ª fatura (amount
em centavos); ignorado quando planId está set.
maxCycles:
type: integer
minimum: 0
exclusiveMinimum: true
nullable: true
description: Número máximo de ciclos; null/ausente = sem fim.
metadata:
type: object
additionalProperties: {}
description: Metadados livres do integrador.
referenceCode:
type: string
minLength: 1
maxLength: 255
description: >-
Código do contrato no sistema do integrador; pesquisável,
sem unicidade.
bootstrapPayment:
type: object
properties:
chargeId:
type: string
minLength: 1
description: ID opaco do charge externo no PSP/gateway.
amount:
type: integer
minimum: 0
exclusiveMinimum: true
description: Valor já cobrado externamente, em centavos.
paidAt:
type: string
format: date-time
description: Data do pagamento externo (ISO 8601 com offset).
method:
type: string
enum:
- card
- pix
- boleto
- other
default: card
description: Método usado na cobrança externa (default 'card').
required:
- chargeId
- amount
- paidAt
description: >-
Comprovante de cobrança externa do ciclo 1 — a Invoice #1
nasce paga; exige defaultPaymentMethodRef e é incompatível
com trial.
trialSpec:
type: object
properties:
durationDays:
type: integer
minimum: 0
requiresPaymentMethod:
type: boolean
required:
- durationDays
- requiresPaymentMethod
description: >-
Override do trial no nível da subscription; mutuamente
exclusivo com bootstrapPayment.
responses:
'201':
description: Assinatura criada
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Identificador único do registro.
number:
type: object
properties:
sequence:
type: integer
description: >-
Número sequencial do documento dentro da numeração
(assinatura ou fatura).
description: Número do endereço.
referenceCode:
type: string
description: >-
Código do contrato no sistema do integrador; pesquisável,
sem unicidade.
nullable: true
customerId:
type: string
description: ID do cliente associado ao registro.
customerEmail:
type: string
description: E-mail do cliente.
customerName:
type: string
description: Nome do cliente.
customerDocument:
type: string
description: Documento do cliente (CPF ou CNPJ).
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
status:
type: string
enum:
- incomplete
- incomplete_expired
- trialing
- active
- past_due
- unpaid
- paused
- canceled
- completed
description: >-
Status atual do registro (assinatura, fatura, plano ou
slip de pagamento).
billingGroupId:
nullable: true
description: >-
ID do grupo de cobrança ao qual o registro pertence; nulo
se não agrupado.
currentPeriodStart:
type: string
format: date-time
description: >-
Início do período de cobrança atual da assinatura (ISO
8601).
currentPeriodEnd:
type: string
format: date-time
description: Fim do período de cobrança atual da assinatura (ISO 8601).
nextInvoiceAt:
type: string
format: date-time
description: >-
Data e hora prevista para a próxima fatura da assinatura
(ISO 8601).
nullable: true
recurrence:
type: object
properties:
interval:
type: integer
description: >-
Quantidade de unidades por ciclo de cobrança (ex.:
interval 3 + unit month = trimestral).
unit:
type: string
description: >-
Unidade do ciclo de cobrança: day, week, month ou
year.
anchor:
type: string
description: >-
Âncora que fixa a data de renovação do ciclo:
subscription_start, day_of_month ou end_of_month.
collectionTiming:
type: string
description: >-
Momento da cobrança do ciclo: prepaid (no início) ou
postpaid (no fim).
description: >-
Regra de recorrência (intervalo, unidade e âncora do
ciclo).
collectionMethod:
type: string
enum:
- charge_automatically
description: >-
Como a fatura é cobrada. Hoje só a cobrança automática na
forma de pagamento padrão.
collectionTiming:
type: string
enum:
- prepaid
- postpaid
description: >-
Momento da cobrança do ciclo: prepaid (no início) ou
postpaid (no fim).
invoiceGenerationMode:
type: string
enum:
- just_in_time
- upfront
description: >-
Modo de geração de faturas: just_in_time (a cada ciclo) ou
upfront (todas antecipadas).
cancelAtPeriodEnd:
type: boolean
description: >-
Indica se a assinatura será cancelada ao fim do período
atual.
canceledAt:
nullable: true
description: >-
Data e hora do cancelamento; nula se não cancelado (ISO
8601).
endedAt:
nullable: true
description: >-
Data e hora em que a assinatura foi efetivamente
encerrada; nula se ainda ativa (ISO 8601).
cancellationReason:
nullable: true
description: Motivo do cancelamento da assinatura.
pausedAt:
nullable: true
description: >-
Data e hora em que a assinatura foi pausada; nula se não
pausada (ISO 8601).
pauseResumesAt:
nullable: true
description: >-
Data e hora agendada para a retomada automática da
assinatura pausada (ISO 8601).
pauseReason:
nullable: true
description: Motivo da pausa da assinatura.
trialEnd:
nullable: true
description: >-
Data e hora de término do período de teste; nula se sem
trial (ISO 8601).
incompleteExpiresAt:
nullable: true
description: >-
Prazo para concluir o primeiro pagamento antes de a
assinatura incompleta expirar (ISO 8601).
trialRemindersFired:
type: array
items: {}
description: >-
Lembretes de fim do período de teste já disparados para a
assinatura.
maxCycles:
nullable: true
description: >-
Número máximo de ciclos da assinatura; nulo se não houver
limite.
issuedCycles:
type: integer
description: >-
Número de ciclos já faturados (faturas emitidas) da
assinatura.
completedCycles:
type: integer
description: Número de ciclos já concluídos (pagos) da assinatura.
defaultPaymentMethodRef:
type: object
properties:
id:
type: string
description: Identificador único do registro.
nullable: true
type:
type: string
description: >-
Tipo da referência: meio da forma de pagamento (card,
pix, boleto) ou natureza da linha da fatura.
description: >-
Referência da forma de pagamento padrão usada para cobrar
a assinatura.
splitConfig:
nullable: true
description: >-
Configuração de divisão (split) dos valores entre
recebedores; nula se sem split.
paymentBehavior:
type: string
enum:
- allow_incomplete
- error_if_incomplete
description: >-
O que fazer quando a primeira cobrança não é aprovada:
allow_incomplete cria a assinatura com a fatura em aberto;
error_if_incomplete cancela a assinatura.
latestInvoiceId:
nullable: true
description: ID da fatura mais recente gerada pela assinatura.
paymentUpdateToken:
nullable: true
description: >-
Token do link público para o cliente atualizar a forma de
pagamento; nulo se não gerado.
paymentUpdateMethods:
nullable: true
description: >-
Formas de pagamento permitidas no link público de troca;
nula se não habilitada.
metadata:
type: object
properties: {}
description: >-
Metadados livres (pares chave-valor) para uso do
integrador; não afeta o processamento.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: Data e hora da última atualização do registro (ISO 8601).
example:
id: sub_hsm2kigu74htdxj3nw2z6f9xw
number:
sequence: 43
referenceCode: CONTRATO-2026-0042
customerId: cust_c72q6ogr9iko0we85mqal04te
customerEmail: maria.silva@example.com
customerName: Maria Silva
customerDocument: '12345678909'
currency: BRL
status: active
billingGroupId: null
currentPeriodStart: '2025-06-29T03:00:00.000Z'
currentPeriodEnd: '2025-07-29T03:00:00.000Z'
nextInvoiceAt: '2025-07-29T03:00:00.000Z'
recurrence:
interval: 1
unit: month
anchor: subscription_start
collectionTiming: prepaid
collectionMethod: charge_automatically
collectionTiming: prepaid
invoiceGenerationMode: just_in_time
cancelAtPeriodEnd: false
canceledAt: null
endedAt: null
cancellationReason: null
pausedAt: null
pauseResumesAt: null
pauseReason: null
trialEnd: null
incompleteExpiresAt: null
trialRemindersFired: []
maxCycles: null
issuedCycles: 0
completedCycles: 0
defaultPaymentMethodRef:
id: crd_tsj66oabsygc9kwvvzt8189f9
type: card
splitConfig: null
paymentBehavior: allow_incomplete
latestInvoiceId: null
paymentUpdateToken: null
paymentUpdateMethods: null
metadata: {}
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.000Z'
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'404':
description: Customer ou price não encontrado
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: NOT_FOUND
message: Subscription not found
'409':
description: Erro de validação (itens, moeda, price arquivado)
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: CONFLICT
message: No refundable payment found
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````