{
  "openapi": "3.1.0",
  "info": {
    "title": "Webmania API 2.0 — selected integration contracts",
    "version": "1.2.0",
    "description": "Reviewed consultation and NFS-e event contracts. This is a scoped contract, not a complete API catalog. Use the linked Markdown product references for issuance, provider-specific fiscal rules and operations not listed here. Documentation versions are independent of API runtime and SDK release versions; routes, authentication and fiscal behavior are unchanged.",
    "contact": {
      "name": "Webmania Engineering",
      "url": "https://webmania.com.br"
    }
  },
  "servers": [
    {
      "url": "https://api.webmania.com.br",
      "description": "Public API base. Select homologation in a supported operation's documented payload, not by guessing another host."
    }
  ],
  "x-coverage": {
    "status": "scoped",
    "operations": 9,
    "includes": [
      "NFS-e consultation and provider capabilities",
      "CT-e, MDF-e, NFCom and DC-e consultation",
      "NFCom service status",
      "NFS-e cancellation and national manifestation"
    ],
    "excludes": [
      "Issuance schemas and operations not listed in this contract"
    ],
    "reviewDate": "2026-10-24"
  },
  "externalDocs": {
    "description": "Official API and documentation changelog",
    "url": "https://webmania.com.br/docs/changelog/"
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "nfse",
      "description": "NFSE selected integration operations"
    },
    {
      "name": "cte",
      "description": "CTE selected integration operations"
    },
    {
      "name": "mdfe",
      "description": "MDFE selected integration operations"
    },
    {
      "name": "nfcom",
      "description": "NFCOM selected integration operations"
    },
    {
      "name": "dce",
      "description": "DCE selected integration operations"
    }
  ],
  "paths": {
    "/2/nfse/consulta/{identifier}": {
      "get": {
        "operationId": "emitterGetNfse",
        "tags": [
          "nfse"
        ],
        "summary": "Consult NFSE by its documented identifier",
        "description": "UUID or order ID (ID). The controller does not resolve a national document key in this path.",
        "externalDocs": {
          "url": "https://webmania.com.br/docs/rest-api-nfse/?format=markdown"
        },
        "parameters": [
          {
            "name": "identifier",
            "in": "path",
            "required": true,
            "description": "UUID or order ID (ID). The controller does not resolve a national document key in this path.",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/FiscalResult"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized401"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden403"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit429"
          },
          "500": {
            "$ref": "#/components/responses/ServerError500"
          },
          "404": {
            "$ref": "#/components/responses/NotFound404"
          },
          "default": {
            "$ref": "#/components/responses/OtherFailure"
          }
        }
      }
    },
    "/2/cte/consulta/{identifier}": {
      "get": {
        "operationId": "emitterGetCte",
        "tags": [
          "cte"
        ],
        "summary": "Consult CTE by its documented identifier",
        "description": "Document UUID or access key; the controller checks length 36 or 44.",
        "externalDocs": {
          "url": "https://webmania.com.br/docs/rest-api-cte/?format=markdown"
        },
        "parameters": [
          {
            "name": "identifier",
            "in": "path",
            "required": true,
            "description": "Document UUID or access key; the controller checks length 36 or 44.",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/FiscalResult"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized401"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden403"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit429"
          },
          "500": {
            "$ref": "#/components/responses/ServerError500"
          },
          "404": {
            "$ref": "#/components/responses/NotFound404"
          },
          "default": {
            "$ref": "#/components/responses/OtherFailure"
          }
        }
      }
    },
    "/2/mdfe/consulta/{key}": {
      "get": {
        "operationId": "emitterGetMdfe",
        "tags": [
          "mdfe"
        ],
        "summary": "Consult MDFE by its documented identifier",
        "description": "MDF-e access key (44 characters) or document UUID (36 characters).",
        "externalDocs": {
          "url": "https://webmania.com.br/docs/rest-api-mdfe/?format=markdown"
        },
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "MDF-e access key (44 characters) or document UUID (36 characters).",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/FiscalResult"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized401"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden403"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit429"
          },
          "500": {
            "$ref": "#/components/responses/ServerError500"
          },
          "404": {
            "$ref": "#/components/responses/NotFound404"
          },
          "default": {
            "$ref": "#/components/responses/OtherFailure"
          }
        }
      }
    },
    "/2/nfcom/consulta/{identifier}": {
      "get": {
        "operationId": "emitterGetNfcom",
        "tags": [
          "nfcom"
        ],
        "summary": "Consult NFCOM by its documented identifier",
        "description": "Document UUID or NFCom access key.",
        "externalDocs": {
          "url": "https://webmania.com.br/docs/rest-api-nfcom/?format=markdown"
        },
        "parameters": [
          {
            "name": "identifier",
            "in": "path",
            "required": true,
            "description": "Document UUID or NFCom access key.",
            "schema": {
              "type": "string",
              "pattern": "^(?:[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}|[0-9]{6}[A-Za-z0-9]{12}[0-9]{26})$"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/FiscalResult"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized401"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden403"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit429"
          },
          "500": {
            "$ref": "#/components/responses/ServerError500"
          },
          "404": {
            "$ref": "#/components/responses/NotFound404"
          },
          "default": {
            "$ref": "#/components/responses/OtherFailure"
          }
        }
      }
    },
    "/2/dce/consulta/{identifier}": {
      "get": {
        "operationId": "emitterGetDce",
        "tags": [
          "dce"
        ],
        "summary": "Consult DCE by its documented identifier",
        "description": "Document identifier supported by DC-e; use the document UUID returned by issuance.",
        "externalDocs": {
          "url": "https://webmania.com.br/docs/rest-api-dce/?format=markdown"
        },
        "parameters": [
          {
            "name": "identifier",
            "in": "path",
            "required": true,
            "description": "Document identifier supported by DC-e; use the document UUID returned by issuance.",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/FiscalResult"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized401"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden403"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit429"
          },
          "500": {
            "$ref": "#/components/responses/ServerError500"
          },
          "404": {
            "$ref": "#/components/responses/NotFound404"
          },
          "default": {
            "$ref": "#/components/responses/OtherFailure"
          }
        }
      }
    },
    "/2/nfse/status": {
      "get": {
        "operationId": "emitterGetNfseProviderStatus",
        "tags": [
          "nfse"
        ],
        "summary": "Get NFSE capabilities or service status",
        "description": "Discover capabilities for the company bound to the bearer token. Inspect status, configured, ambientes, emissao and parametros_disponiveis when present. HTTP 200 may contain status=false and error.",
        "parameters": [
          {
            "name": "todos_servicos",
            "in": "query",
            "required": false,
            "description": "Outside the National Standard, request all municipal service codes instead of filtering them by the company's CNAE codes. Read as a boolean flag; omission keeps CNAE filtering when company CNAE codes are available. This flag does not change National Standard service-code discovery.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON result; read fiscal status and error fields before accepting it as a business success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "status": {
                      "type": "boolean"
                    },
                    "configured": {
                      "type": "boolean"
                    },
                    "ambientes": {
                      "type": "array",
                      "items": {
                        "type": "integer"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized401"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden403"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit429"
          },
          "500": {
            "$ref": "#/components/responses/ServerError500"
          },
          "default": {
            "$ref": "#/components/responses/OtherFailure"
          }
        }
      }
    },
    "/2/nfcom/status": {
      "get": {
        "operationId": "emitterGetNfcomServiceStatus",
        "tags": [
          "nfcom"
        ],
        "summary": "Get NFCOM capabilities or service status",
        "description": "Consult NFCom service availability. HTTP 503 can include the provider result when operacional=false.",
        "responses": {
          "200": {
            "description": "JSON result; read fiscal status and error fields before accepting it as a business success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "operacional": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized401"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden403"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit429"
          },
          "500": {
            "$ref": "#/components/responses/ServerError500"
          },
          "default": {
            "$ref": "#/components/responses/OtherFailure"
          }
        }
      }
    },
    "/2/nfse/cancelar": {
      "put": {
        "operationId": "emitterCancelNfse",
        "tags": [
          "nfse"
        ],
        "summary": "Cancel NFS-e",
        "description": "Supply uuid or codigo_verificacao. At base validation, motivo is optional and accepts 1, 2 or 4 when supplied; justificativa is optional and accepts 15-255 characters when supplied. Scheduled documents cancel their scheduling without a provider submission. Regular approved documents require motivo and remain subject to certificate, municipality and environment eligibility. Simplified documents follow a separate cancellation path with defaults for omitted motivo and justificativa; that path does not broaden the public validation enum. Base validation failures return HTTP 200 with an error field, not HTTP 422. Validation acceptance is not fiscal success; provider eligibility and the final outcome require the full reference.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NFSeCancellation"
              },
              "examples": {
                "sample": {
                  "summary": "Validation example only; not proof of cancellation eligibility or success",
                  "value": {
                    "uuid": "00000000-0000-0000-0000-000000000000",
                    "motivo": 2
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/FiscalResult"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized401"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden403"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit429"
          },
          "500": {
            "$ref": "#/components/responses/ServerError500"
          },
          "404": {
            "$ref": "#/components/responses/NotFound404"
          },
          "default": {
            "$ref": "#/components/responses/OtherFailure"
          }
        }
      }
    },
    "/2/nfse/manifestar": {
      "put": {
        "operationId": "emitterManifestNfse",
        "tags": [
          "nfse"
        ],
        "summary": "Register national NFS-e manifestation",
        "description": "Base validation requires ambiente, chave, manifestador and evento. motivo_rejeicao is required only when evento=2; justificativa_rejeicao is required when motivo_rejeicao=9, not for every rejection. If supplied in other cases, these fields still follow their enum and length rules. Base validation failures return HTTP 200 with an error field, not HTTP 422. Manifestation is restricted to the National Standard and requires an eligible municipality and certificate. The processing step reads both rejection fields; when rejecting (evento=2), send motivo_rejeicao and, for motivo_rejeicao=9, justificativa_rejeicao, because omitting a field the processing step reads is not guaranteed to succeed. Passing validation is not proof of a registered fiscal event; see the full reference for eligibility and the final outcome.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NFSeManifestation"
              },
              "examples": {
                "sample": {
                  "summary": "Rejection validation example only; not a registered fiscal event",
                  "value": {
                    "ambiente": 2,
                    "chave": "00000000000000000000000000000000000000000000000000",
                    "manifestador": 1,
                    "evento": 2,
                    "motivo_rejeicao": 9,
                    "justificativa_rejeicao": "Manifestacao ilustrativa de rejeicao."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/FiscalResult"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized401"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden403"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit429"
          },
          "500": {
            "$ref": "#/components/responses/ServerError500"
          },
          "404": {
            "$ref": "#/components/responses/NotFound404"
          },
          "default": {
            "$ref": "#/components/responses/OtherFailure"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Company API 2.0 access token from the Webmania panel. The route group also checks the issue ability and product subscription."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Error envelopes depend on the rejecting layer. Inspect HTTP status and the body; message can also be informational.",
        "properties": {
          "error": {},
          "message": {
            "type": "string"
          },
          "msg": {
            "type": "string"
          },
          "errors": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "FiscalSnapshot": {
        "type": "object",
        "description": "Product-specific fiscal snapshot. Fields depend on model, provider and processing phase. A UUID or HTTP 200 is not proof of authorization.",
        "properties": {
          "uuid": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "chave": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      },
      "NFSeCancellation": {
        "type": "object",
        "description": "Base validation accepts uuid or codigo_verificacao; motivo and justificativa are optional at this layer. Regular approved cancellation requires motivo; scheduled and simplified cancellation have distinct paths. Neither validation nor this schema proves provider eligibility or fiscal success. Send uuid or codigo_verificacao with a non-empty value; an empty string is not guaranteed to be treated as an omitted field. The identifier conditionals below require property presence but do not fully model the server's empty-value handling. In particular, codigo_verificacao has no unconditional minimum length rule. Missing, null, empty, whitespace-only and wrong-type values are not guaranteed to behave identically; use non-empty document identifiers. String inputs are trimmed and empty strings are converted to null before validation; length bounds apply to the trimmed value, so an identifier padded with leading or trailing spaces is measured after trimming.",
        "properties": {
          "codigo_verificacao": {
            "description": "Alternative identifier; required when uuid is absent or empty. When both identifiers are supplied, codigo_verificacao takes precedence for lookup. Send a non-empty value; see the schema-level guidance above.",
            "type": "string"
          },
          "uuid": {
            "description": "Required when codigo_verificacao is absent or empty; exactly 36 characters when validated. Send a non-empty value; see the schema-level guidance.",
            "type": "string",
            "minLength": 36,
            "maxLength": 36
          },
          "motivo": {
            "description": "Optional at base validation; required for regular approved cancellation. Simplified cancellation defaults an omitted reason and has separate service constraints; do not infer that reason 9 is accepted by this public request validator.",
            "enum": [
              1,
              2,
              4,
              "1",
              "2",
              "4"
            ]
          },
          "justificativa": {
            "description": "Optional at base validation; 15-255 characters when supplied. Provider-specific cancellation requirements still apply.",
            "type": "string",
            "minLength": 15,
            "maxLength": 255
          }
        },
        "allOf": [
          {
            "if": {
              "anyOf": [
                {
                  "not": {
                    "required": [
                      "uuid"
                    ],
                    "properties": {
                      "uuid": {
                        "not": {
                          "enum": [
                            null,
                            "",
                            [],
                            {}
                          ]
                        }
                      }
                    }
                  }
                }
              ]
            },
            "then": {
              "required": [
                "codigo_verificacao"
              ],
              "properties": {
                "codigo_verificacao": {},
                "uuid": {},
                "motivo": {},
                "justificativa": {}
              }
            }
          },
          {
            "if": {
              "anyOf": [
                {
                  "not": {
                    "required": [
                      "codigo_verificacao"
                    ],
                    "properties": {
                      "codigo_verificacao": {
                        "not": {
                          "enum": [
                            null,
                            "",
                            [],
                            {}
                          ]
                        }
                      }
                    }
                  }
                }
              ]
            },
            "then": {
              "required": [
                "uuid"
              ],
              "properties": {
                "codigo_verificacao": {},
                "uuid": {},
                "motivo": {},
                "justificativa": {}
              }
            }
          }
        ],
        "additionalProperties": true
      },
      "NFSeManifestation": {
        "type": "object",
        "description": "Base validation requires ambiente, chave, manifestador and evento. Rejection reason is required only for evento=2; rejection justification is required whenever motivo_rejeicao=9. Supplied optional fields still follow their validation rules. Processing still reads both rejection fields unconditionally, so a validation-accepted request omitting them is not a proven successful fiscal event. Send each field with its documented type and a non-empty value; empty strings and type-coerced values are not guaranteed to be accepted as omitted. Provider and certificate eligibility are separate from this validation schema.",
        "required": [
          "ambiente",
          "chave",
          "manifestador",
          "evento"
        ],
        "properties": {
          "ambiente": {
            "enum": [
              1,
              2,
              "1",
              "2"
            ]
          },
          "chave": {
            "type": "string",
            "minLength": 50,
            "maxLength": 50
          },
          "manifestador": {
            "enum": [
              1,
              2,
              "1",
              "2"
            ]
          },
          "evento": {
            "description": "1 confirms the document; 2 rejects it.",
            "enum": [
              1,
              2,
              "1",
              "2"
            ]
          },
          "motivo_rejeicao": {
            "description": "Required only when evento=2; allowed reasons apply whenever supplied.",
            "enum": [
              1,
              2,
              3,
              4,
              5,
              9,
              "1",
              "2",
              "3",
              "4",
              "5",
              "9"
            ]
          },
          "justificativa_rejeicao": {
            "description": "Required when motivo_rejeicao=9, even if that reason is supplied with evento=1; otherwise optional. When supplied, use 15-255 characters.",
            "type": "string",
            "minLength": 15,
            "maxLength": 255
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "evento": {
                  "enum": [
                    2,
                    "2"
                  ]
                }
              },
              "required": [
                "evento"
              ]
            },
            "then": {
              "required": [
                "motivo_rejeicao"
              ]
            }
          },
          {
            "if": {
              "properties": {
                "motivo_rejeicao": {
                  "enum": [
                    9,
                    "9"
                  ]
                }
              },
              "required": [
                "motivo_rejeicao"
              ]
            },
            "then": {
              "required": [
                "justificativa_rejeicao"
              ]
            }
          }
        ],
        "additionalProperties": true
      }
    },
    "responses": {
      "FiscalResult": {
        "description": "JSON result; read fiscal status and error fields before accepting it as a business success.",
        "content": {
          "application/json": {
            "schema": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/FiscalSnapshot"
                },
                {
                  "$ref": "#/components/schemas/Error"
                }
              ]
            }
          }
        }
      },
      "Unauthorized401": {
        "description": "Missing or invalid bearer token (HTTP 401).",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            },
            "example": {
              "error": "Acesso restrito. Token não informado ou inválido."
            }
          }
        }
      },
      "Forbidden403": {
        "description": "Access, ability or subscription denied (HTTP 403).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Acesso restrito."
            }
          }
        }
      },
      "NotFound404": {
        "description": "Resource or fiscal document not found (HTTP 404). Some business-level document errors instead return HTTP 200 with error; always inspect the body.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Documento fiscal não localizado."
            }
          }
        }
      },
      "ValidationError422": {
        "description": "HTTP 422 for a validation exception handled by the API exception handler. NFS-e cancellation and manifestation return HTTP 200 with a single error field on request validation failure.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error",
                "errors"
              ],
              "properties": {
                "error": {
                  "type": "string",
                  "const": "validation_failed"
                },
                "errors": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              },
              "additionalProperties": true
            },
            "example": {
              "error": "validation_failed",
              "errors": {
                "uuid": [
                  "O campo uuid é obrigatório."
                ]
              }
            }
          }
        }
      },
      "RateLimit429": {
        "description": "Request rate limit exceeded (HTTP 429). Honor Retry-After when present.",
        "headers": {
          "Retry-After": {
            "description": "Delay in seconds before retrying, when supplied by the limiter.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerError500": {
        "description": "Unexpected server failure (HTTP 500). The error field contains a customer-facing message, not internal exception details.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "OtherFailure": {
        "description": "Other middleware, provider or service error; inspect the HTTP status and body.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}