{
  "openapi": "3.1.0",
  "info": {
    "title": "Canal API Oficial",
    "version": "1.0.0",
    "description": "API oficial do WhatsApp (Cloud API da Meta) para o seu sistema, operada pela Soluções de IA.\n\n**Autenticação:** OAuth2 client_credentials. Troque client_id + client_secret por um token de 1 hora em `POST /oauth/token` e envie `Authorization: Bearer <access_token>`.\n\n**Idempotência:** envie `client_message_id` (ou o cabeçalho `Idempotency-Key`). Repetir a mesma chave devolve a mesma resposta com `idempotent_replayed: true` e nada é reenviado.\n\n**Webhooks:** os eventos chegam no seu endpoint assinados com HMAC-SHA256 de `<X-Canal-Timestamp>.<corpo>` usando o segredo do webhook, no cabeçalho `X-Canal-Signature: v1=<hex>`.\n\n**Erros de validação (422):** `{error:{code, message, param, errors:[...]}}` com todos os problemas de uma vez."
  },
  "servers": [
    {
      "url": "https://canalapioficial.solucoesdeia.com",
      "description": "Teste (este ambiente: use credencial sandbox)"
    },
    {
      "url": "https://canalapioficial.solucoesdeia.com",
      "description": "Produção"
    }
  ],
  "security": [
    {
      "oauth2": []
    }
  ],
  "tags": [
    {
      "name": "Autenticação"
    },
    {
      "name": "Mensagens"
    },
    {
      "name": "Templates"
    },
    {
      "name": "Mídia"
    },
    {
      "name": "Eventos"
    },
    {
      "name": "Contatos"
    },
    {
      "name": "Números"
    },
    {
      "name": "Webhooks"
    },
    {
      "name": "Saúde"
    }
  ],
  "paths": {
    "/oauth/token": {
      "post": {
        "tags": [
          "Autenticação"
        ],
        "summary": "Gerar token de acesso (client_credentials)",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type",
                  "client_id",
                  "client_secret"
                ],
                "properties": {
                  "grant_type": {
                    "const": "client_credentials"
                  },
                  "client_id": {
                    "type": "string"
                  },
                  "client_secret": {
                    "type": "string"
                  },
                  "scope": {
                    "type": "string",
                    "description": "Opcional: subconjunto dos escopos da credencial, separados por espaço"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "type": "string"
                    },
                    "token_type": {
                      "const": "Bearer"
                    },
                    "expires_in": {
                      "type": "integer",
                      "example": 3600
                    },
                    "scope": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "unsupported_grant_type / invalid_scope"
          },
          "401": {
            "description": "invalid_client"
          },
          "403": {
            "description": "access_denied (IP fora da lista ou empresa suspensa)"
          },
          "429": {
            "description": "slow_down"
          }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "tags": [
          "Mensagens"
        ],
        "summary": "Enviar mensagem (template, texto, mídia ou interativa)",
        "security": [
          {
            "oauth2": [
              "messages:send"
            ]
          }
        ],
        "parameters": [
          {
            "name": "dry_run",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "true = só valida e devolve categoria, custo informativo e capacidade do número"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Alternativa ao client_message_id. Mesma chave + mesmo corpo = mesma resposta, nada é reenviado."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnvioMensagem"
              },
              "example": {
                "to": "5531999990000",
                "client_message_id": "fatura-2026-10-8841",
                "template": {
                  "name": "boleto_mensal",
                  "language": "pt_BR",
                  "variables": {
                    "nome": "Ana",
                    "valor": 35000,
                    "vencimento": "2026-10-30"
                  },
                  "header": {
                    "document": {
                      "url": "https://erp.cliente.com.br/boletos/8841.pdf",
                      "filename": "Fatura outubro 2026.pdf"
                    }
                  },
                  "buttons": {
                    "copy_code": "23793381286000000000300000000400198760000035000",
                    "url_suffix": "8841"
                  }
                },
                "metadata": {
                  "ref": "8841"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "dry_run válido",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DryRun"
                }
              }
            }
          },
          "202": {
            "description": "Aceita (status queued). Acompanhe pelos webhooks ou GET /v1/messages/{id}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Mensagem"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "409": {
            "description": "idempotency_in_progress",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "422": {
            "description": "Validação: template_not_approved, template_not_found, invalid_phone, contact_opted_out, template_variables_mismatch, media_invalid, outside_window, number_not_found, idempotency_conflict, meta_error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "502": {
            "description": "A Meta respondeu erro 5xx",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Mensagens"
        ],
        "summary": "Listar mensagens (mais recentes primeiro)",
        "security": [
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "next_cursor da página anterior"
          },
          {
            "name": "contact",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "schema": {
              "enum": [
                "inbound",
                "outbound"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "enum": [
                "queued",
                "sent",
                "delivered",
                "read",
                "failed",
                "received",
                "unknown"
              ]
            }
          },
          {
            "name": "client_message_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Página",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Mensagem"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages/{id}": {
      "get": {
        "tags": [
          "Mensagens"
        ],
        "summary": "Status e linha do tempo de uma mensagem (id ou wamid)",
        "security": [
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Mensagem com timeline",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Mensagem"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "404": {
            "description": "Não encontrada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/conversations": {
      "get": {
        "tags": [
          "Mensagens"
        ],
        "summary": "Conversas por contato (última mensagem, janela de 24 h)",
        "security": [
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "next_cursor da página anterior"
          }
        ],
        "responses": {
          "200": {
            "description": "Página"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/conversations/{contact}/messages": {
      "get": {
        "tags": [
          "Mensagens"
        ],
        "summary": "Mensagens de um contato",
        "security": [
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "contact",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "next_cursor da página anterior"
          }
        ],
        "responses": {
          "200": {
            "description": "Página"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/templates": {
      "get": {
        "tags": [
          "Templates"
        ],
        "summary": "Listar templates",
        "security": [
          {
            "oauth2": [
              "templates:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "enum": [
                "approved",
                "pending",
                "rejected",
                "paused",
                "disabled"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "enum": [
                "utility",
                "marketing",
                "authentication"
              ]
            }
          },
          {
            "name": "has",
            "in": "query",
            "schema": {
              "enum": [
                "document_header",
                "image_header",
                "video_header",
                "buttons",
                "url_button",
                "copy_code"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Templates"
        ],
        "summary": "Criar template e enviar para aprovação da Meta",
        "security": [
          {
            "oauth2": [
              "templates:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Alternativa ao client_message_id. Mesma chave + mesmo corpo = mesma resposta, nada é reenviado."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "category"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "pattern": "^[a-z0-9_]+$"
                  },
                  "language": {
                    "type": "string",
                    "default": "pt_BR"
                  },
                  "category": {
                    "enum": [
                      "UTILITY",
                      "MARKETING",
                      "AUTHENTICATION"
                    ]
                  },
                  "parameter_format": {
                    "enum": [
                      "NAMED",
                      "POSITIONAL"
                    ]
                  },
                  "components": {
                    "type": "array",
                    "description": "Formato da Meta (HEADER, BODY, FOOTER, BUTTONS)"
                  },
                  "library_template_name": {
                    "type": "string",
                    "description": "Criar a partir da biblioteca da Meta"
                  },
                  "variables": {
                    "type": "object",
                    "additionalProperties": {
                      "$ref": "#/components/schemas/DefVariavel"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Criado (status pending; a aprovação chega pelo webhook template.status)"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "422": {
            "description": "Validação ou recusa da Meta",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/templates/sync": {
      "post": {
        "tags": [
          "Templates"
        ],
        "summary": "Sincronizar com a Meta",
        "security": [
          {
            "oauth2": [
              "templates:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Total sincronizado"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/templates/library": {
      "get": {
        "tags": [
          "Templates"
        ],
        "summary": "Biblioteca de templates prontos da Meta",
        "security": [
          {
            "oauth2": [
              "templates:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "topic",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "language",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/templates/by-name/{name}/{lang}": {
      "get": {
        "tags": [
          "Templates"
        ],
        "summary": "Template pelo nome estável",
        "security": [
          {
            "oauth2": [
              "templates:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Template"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "404": {
            "description": "Não encontrado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/templates/{id}": {
      "get": {
        "tags": [
          "Templates"
        ],
        "summary": "Template por id",
        "security": [
          {
            "oauth2": [
              "templates:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Template"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/templates/{id}/schema": {
      "get": {
        "tags": [
          "Templates"
        ],
        "summary": "Schema: variáveis tipadas, cabeçalho e parâmetros de botão",
        "security": [
          {
            "oauth2": [
              "templates:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Schema",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SchemaTemplate"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Templates"
        ],
        "summary": "Definir os tipos das variáveis",
        "security": [
          {
            "oauth2": [
              "templates:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "variables": {
                    "type": "object",
                    "additionalProperties": {
                      "$ref": "#/components/schemas/DefVariavel"
                    }
                  }
                }
              },
              "example": {
                "variables": {
                  "valor": {
                    "type": "currency",
                    "format": "BRL"
                  },
                  "vencimento": {
                    "type": "date",
                    "format": "dd/MM/yyyy"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Schema atualizado"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/templates/{id}/preview": {
      "post": {
        "tags": [
          "Templates"
        ],
        "summary": "Prévia do texto com as variáveis formatadas",
        "security": [
          {
            "oauth2": [
              "templates:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "variables": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Prévia"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/media": {
      "post": {
        "tags": [
          "Mídia"
        ],
        "summary": "Subir mídia (url ou base64) e receber media_id válido por 30 dias",
        "security": [
          {
            "oauth2": [
              "messages:send"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Alternativa ao client_message_id. Mesma chave + mesmo corpo = mesma resposta, nada é reenviado."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "base64": {
                    "type": "string"
                  },
                  "mime_type": {
                    "type": "string"
                  },
                  "filename": {
                    "type": "string"
                  },
                  "from": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Mídia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "example": "med_..."
                    },
                    "expires_at": {
                      "type": "string"
                    },
                    "cached": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "422": {
            "description": "media_invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/media/{id}": {
      "get": {
        "tags": [
          "Mídia"
        ],
        "summary": "Baixar mídia recebida (media_id da mensagem recebida)",
        "security": [
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Arquivo"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events": {
      "post": {
        "tags": [
          "Eventos"
        ],
        "summary": "Disparar evento do seu sistema (vira o template configurado)",
        "security": [
          {
            "oauth2": [
              "messages:send"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Alternativa ao client_message_id. Mesma chave + mesmo corpo = mesma resposta, nada é reenviado."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "event",
                  "to"
                ],
                "properties": {
                  "event": {
                    "type": "string"
                  },
                  "to": {
                    "type": "string"
                  },
                  "client_message_id": {
                    "type": "string"
                  },
                  "variables": {
                    "type": "object"
                  },
                  "header": {
                    "type": "object"
                  },
                  "buttons": {
                    "type": "object"
                  },
                  "metadata": {
                    "type": "object"
                  }
                }
              },
              "example": {
                "event": "reserva_confirmada",
                "to": "5561999990000",
                "client_message_id": "reserva-4471-confirmacao",
                "variables": {
                  "nome": "Carla",
                  "checkin": "2026-12-20",
                  "valor": 128000
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Mensagem aceita",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Mensagem"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "404": {
            "description": "event_not_configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "422": {
            "description": "Validação",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/event-triggers": {
      "get": {
        "tags": [
          "Eventos"
        ],
        "summary": "Listar eventos configurados",
        "security": [
          {
            "oauth2": [
              "templates:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Lista"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Eventos"
        ],
        "summary": "Configurar evento -> template",
        "security": [
          {
            "oauth2": [
              "templates:write"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "event",
                  "template"
                ],
                "properties": {
                  "event": {
                    "type": "string"
                  },
                  "template": {
                    "type": "string"
                  },
                  "language": {
                    "type": "string"
                  },
                  "from": {
                    "type": "string"
                  },
                  "active": {
                    "type": "boolean"
                  },
                  "variables_map": {
                    "type": "object",
                    "description": "Só para template posicional ({{1}}): {body:[\"nome\",\"data\"]}"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Configurado"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/event-triggers/{event}": {
      "delete": {
        "tags": [
          "Eventos"
        ],
        "summary": "Remover evento",
        "security": [
          {
            "oauth2": [
              "templates:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "event",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Removido"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/contacts/{phone}/opt-out": {
      "get": {
        "tags": [
          "Contatos"
        ],
        "summary": "Consultar opt-out",
        "security": [
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "phone",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Situação"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Contatos"
        ],
        "summary": "Registrar opt-out (nada mais sai para o contato)",
        "security": [
          {
            "oauth2": [
              "messages:send"
            ]
          }
        ],
        "parameters": [
          {
            "name": "phone",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Registrado"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Contatos"
        ],
        "summary": "Remover opt-out (o contato pediu para voltar)",
        "security": [
          {
            "oauth2": [
              "messages:send"
            ]
          }
        ],
        "parameters": [
          {
            "name": "phone",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removido"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/numbers": {
      "get": {
        "tags": [
          "Números"
        ],
        "summary": "Números da empresa (qualidade e limite)",
        "security": [
          {
            "oauth2": [
              "messages:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Lista"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/numbers/embedded-signup": {
      "post": {
        "tags": [
          "Números"
        ],
        "summary": "Concluir o cadastro incorporado (code do FB.login com o nosso config_id)",
        "security": [
          {
            "oauth2": [
              "numbers:manage"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "waba_id": {
                    "type": "string"
                  },
                  "phone_number_id": {
                    "type": "string"
                  },
                  "pin": {
                    "type": "string",
                    "pattern": "^\\d{6}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Número conectado e registrado"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "502": {
            "description": "Falha numa etapa da Meta (step informado)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "503": {
            "description": "Cadastro incorporado desligado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Listar webhooks",
        "security": [
          {
            "oauth2": [
              "webhooks:manage"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Lista"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Cadastrar webhook (o secret aparece só nesta resposta)",
        "security": [
          {
            "oauth2": [
              "webhooks:manage"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "default": [
                      "*"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Criado com secret"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks/{id}": {
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Desativar webhook",
        "security": [
          {
            "oauth2": [
              "webhooks:manage"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Desativado"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhook-deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Entregas (pending, delivered, dead)",
        "security": [
          {
            "oauth2": [
              "webhooks:manage"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "next_cursor da página anterior"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "enum": [
                "pending",
                "delivered",
                "dead"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Página"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhook-deliveries/{id}/resend": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Reenviar entrega (inclusive da fila morta)",
        "security": [
          {
            "oauth2": [
              "webhooks:manage"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado da nova tentativa"
          },
          "401": {
            "description": "Token ausente, inválido, expirado ou de credencial revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "402": {
            "description": "Empresa suspensa por pendência comercial",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou IP fora da lista",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite por minuto da credencial atingido (veja Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/v1/health": {
      "get": {
        "tags": [
          "Saúde"
        ],
        "summary": "Saúde do serviço",
        "security": [],
        "responses": {
          "200": {
            "description": "ok"
          },
          "503": {
            "description": "banco indisponível"
          }
        }
      }
    }
  },
  "webhooks": {
    "evento": {
      "post": {
        "summary": "Evento entregue no seu endpoint",
        "description": "Tipos: message.queued, message.sent, message.delivered, message.read, message.failed (com meta_error), message.received, button.clicked, contact.opted_out, template.status, number.quality. Cabeçalhos: X-Canal-Event, X-Canal-Delivery, X-Canal-Timestamp, X-Canal-Signature (v1=HMAC-SHA256 de timestamp.corpo). Responda 2xx em até 8 s; senão tentamos de novo em 1 min, 5 min, 30 min, 2 h e 6 h.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "tenant": {
                    "type": "string"
                  },
                  "data": {
                    "type": "object"
                  }
                }
              },
              "example": {
                "id": "6c1f...",
                "type": "message.delivered",
                "created_at": "2026-11-18T10:00:00Z",
                "tenant": "hotel-pires",
                "data": {
                  "message": {
                    "id": "0d7e...",
                    "status": "delivered",
                    "to": "5531999990000",
                    "client_message_id": "fatura-2026-10-8841"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recebido"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://canalapioficial.solucoesdeia.com/oauth/token",
            "scopes": {
              "messages:send": "Enviar mensagens, eventos, mídia, opt-out",
              "messages:read": "Ler mensagens, conversas, números",
              "templates:read": "Ler templates e eventos configurados",
              "templates:write": "Criar templates e configurar eventos",
              "webhooks:manage": "Gerenciar webhooks e entregas",
              "numbers:manage": "Conectar números (cadastro incorporado)"
            }
          }
        }
      }
    },
    "schemas": {
      "Erro": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "param": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "errors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "param": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "DefVariavel": {
        "type": "object",
        "properties": {
          "type": {
            "enum": [
              "string",
              "currency",
              "date",
              "number"
            ]
          },
          "required": {
            "type": "boolean"
          },
          "max_length": {
            "type": "integer"
          },
          "format": {
            "type": "string",
            "example": "dd/MM/yyyy"
          },
          "example": {},
          "default": {}
        }
      },
      "SchemaTemplate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "parameter_format": {
            "enum": [
              "NAMED",
              "POSITIONAL"
            ]
          },
          "variables": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/DefVariavel"
            }
          },
          "header": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "type": {
                "type": "string"
              },
              "required": {
                "type": "boolean"
              },
              "accepts": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "max_bytes": {
                "type": "integer"
              }
            }
          },
          "buttons": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "type": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                },
                "param": {
                  "enum": [
                    "url_suffix",
                    "copy_code"
                  ]
                },
                "required": {
                  "type": "boolean"
                }
              }
            }
          }
        }
      },
      "EnvioMensagem": {
        "type": "object",
        "required": [
          "to"
        ],
        "properties": {
          "to": {
            "type": "string",
            "description": "E.164 sem +, só dígitos",
            "example": "5531999990000"
          },
          "from": {
            "type": "string",
            "description": "phone_number_id (obrigatório se a empresa tiver mais de um número)"
          },
          "client_message_id": {
            "type": "string",
            "description": "Sua chave de idempotência"
          },
          "type": {
            "enum": [
              "template",
              "text",
              "image",
              "video",
              "audio",
              "document",
              "sticker",
              "interactive"
            ],
            "description": "Opcional quando há template"
          },
          "template": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "language": {
                "type": "string",
                "default": "pt_BR"
              },
              "variables": {
                "type": "object",
                "description": "Por nome; currency em centavos (inteiro), date em ISO (AAAA-MM-DD)"
              },
              "header": {
                "type": "object",
                "description": "{document:{url,filename}|{media_id}} | {image:{url}|{media_id}} | {video:{...}}"
              },
              "buttons": {
                "type": "object",
                "properties": {
                  "copy_code": {
                    "type": "string"
                  },
                  "url_suffix": {
                    "type": "string"
                  },
                  "quick_reply": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "text": {
            "type": "object",
            "properties": {
              "body": {
                "type": "string",
                "maxLength": 4096
              },
              "preview_url": {
                "type": "boolean"
              }
            }
          },
          "media": {
            "type": "object",
            "properties": {
              "link": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "caption": {
                "type": "string"
              },
              "filename": {
                "type": "string"
              }
            }
          },
          "interactive": {
            "type": "object",
            "description": "button: até 3 botões (título até 20). list: até 10 opções no total.",
            "properties": {
              "type": {
                "enum": [
                  "button",
                  "list"
                ]
              },
              "body": {
                "type": "string"
              },
              "header": {
                "type": "string"
              },
              "footer": {
                "type": "string"
              },
              "buttons": {
                "type": "array",
                "maxItems": 3
              },
              "button": {
                "type": "string"
              },
              "sections": {
                "type": "array"
              }
            }
          },
          "metadata": {
            "type": "object",
            "description": "Devolvido nos webhooks e consultas"
          },
          "track_links": {
            "type": "boolean",
            "description": "Fase 2 (aceito e ignorado, com aviso)"
          }
        }
      },
      "Mensagem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "wamid": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "enum": [
              "queued",
              "sent",
              "delivered",
              "read",
              "failed",
              "received",
              "unknown"
            ]
          },
          "direction": {
            "enum": [
              "outbound",
              "inbound"
            ]
          },
          "to": {
            "type": "string"
          },
          "from": {
            "type": "string"
          },
          "contact": {
            "type": "string"
          },
          "template": {
            "type": "object"
          },
          "conversation": {
            "type": "object",
            "properties": {
              "category": {
                "type": "string"
              }
            }
          },
          "client_message_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {},
          "estimated_cost_cents": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Informativo: a Meta cobra a sua conta direto"
          },
          "error": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "meta_error": {
                "type": "integer"
              },
              "detail": {
                "type": "string"
              }
            }
          },
          "idempotent_replayed": {
            "type": "boolean"
          },
          "sandbox": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string"
          },
          "timeline": {
            "type": "array"
          }
        }
      },
      "DryRun": {
        "type": "object",
        "properties": {
          "dry_run": {
            "const": true
          },
          "valid": {
            "type": "boolean"
          },
          "conversation_category": {
            "type": "string"
          },
          "estimated_cost_cents": {
            "type": "integer"
          },
          "window_open": {
            "type": "boolean"
          },
          "number": {
            "type": "object",
            "properties": {
              "tier": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "remaining_today": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "quality_rating": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}