{
  "openapi": "3.1.1",
  "info": {
    "title": "API CFDI Layer",
    "description": "Validación de CFDI 4.0 ante el SAT para apps y sistemas. Autenticación: token de sesión (Authorization: Bearer) o llave API (X-Api-Key).",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://app.cfdilayer.com/"
    }
  ],
  "paths": {
    "/salud": {
      "get": {
        "tags": [
          "Estado"
        ],
        "summary": "Estado del servicio",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/planes": {
      "get": {
        "tags": [
          "Cuenta"
        ],
        "summary": "Planes y precios vigentes",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/sesion/iniciar": {
      "post": {
        "tags": [
          "Sesión"
        ],
        "summary": "Inicia sesión y devuelve el token de acceso y el de renovación",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IniciarSesionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/sesion/renovar": {
      "post": {
        "tags": [
          "Sesión"
        ],
        "summary": "Cambia el token de renovación por tokens nuevos (el anterior deja de servir)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RenovarSesionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/sesion/cerrar": {
      "post": {
        "tags": [
          "Sesión"
        ],
        "summary": "Cierra la sesión: el token de renovación deja de servir",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RenovarSesionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/cuenta": {
      "get": {
        "tags": [
          "Cuenta"
        ],
        "summary": "Datos de la cuenta",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/cuenta/consumo": {
      "get": {
        "tags": [
          "Cuenta"
        ],
        "summary": "Consumo y saldo: verificaciones y auditorías del día, y consultas del mes hechas con llave API",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/llaves": {
      "get": {
        "tags": [
          "Llaves API"
        ],
        "summary": "Llaves API de la cuenta",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "post": {
        "tags": [
          "Llaves API"
        ],
        "summary": "Crea una llave API. La llave completa solo se devuelve en esta respuesta",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrearLlaveRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/llaves/{id}": {
      "delete": {
        "tags": [
          "Llaves API"
        ],
        "summary": "Revoca una llave API (deja de funcionar de inmediato)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/verificaciones": {
      "post": {
        "tags": [
          "Validaciones"
        ],
        "summary": "Verificación rápida: vigente o cancelado ante el SAT y emisor en lista 69-B",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerificarRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/auditorias": {
      "post": {
        "tags": [
          "Validaciones"
        ],
        "summary": "Auditoría avanzada de un XML: esquema, sello, certificado, estatus SAT, lista 69-B y score",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditarRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/historial": {
      "get": {
        "tags": [
          "Historial"
        ],
        "summary": "Validaciones de la cuenta, de la más reciente a la más antigua",
        "parameters": [
          {
            "name": "pagina",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "tamano",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32",
              "default": 20
            }
          },
          {
            "name": "tipo",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/TipoUso"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/historial/{id}": {
      "get": {
        "tags": [
          "Historial"
        ],
        "summary": "Una validación con el detalle guardado de la respuesta",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/historial/{id}/xml": {
      "get": {
        "tags": [
          "Historial"
        ],
        "summary": "El XML guardado de una auditoría (solo cuentas; desde el 3-oct-2026)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/historial/{id}/auditar": {
      "post": {
        "tags": [
          "Historial"
        ],
        "summary": "Vuelve a auditar el XML guardado: queda como una auditoría nueva y descuenta una del saldo",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/historial/{id}/pdf": {
      "get": {
        "tags": [
          "Historial"
        ],
        "summary": "PDF de una auditoría del historial: tipo=dictamen (resumen de la auditoría) o tipo=factura (representación impresa con conceptos, sellos y QR)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "tipo",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "dictamen"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/facturas/{uuid}/pagos": {
      "get": {
        "tags": [
          "Complementos de pago"
        ],
        "summary": "Complementos de pago, notas de crédito y saldo de una factura de tu bóveda (no descuenta consultas)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "incluirXml",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/pagos": {
      "get": {
        "tags": [
          "Complementos de pago"
        ],
        "summary": "Complementos de pago que entraron a tu bóveda o se cancelaron desde una fecha, paginados, para sincronizar (no descuenta consultas)",
        "parameters": [
          {
            "name": "desde",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "corte",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "rfc",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pagina",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "tamano",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32",
              "default": 100
            }
          },
          {
            "name": "incluirXml",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AuditarRequest": {
        "required": [
          "xmlBase64"
        ],
        "type": "object",
        "properties": {
          "xmlBase64": {
            "type": [
              "null",
              "string"
            ]
          },
          "nombreArchivo": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "CrearLlaveRequest": {
        "required": [
          "nombre"
        ],
        "type": "object",
        "properties": {
          "nombre": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "IniciarSesionRequest": {
        "required": [
          "correo",
          "contrasena"
        ],
        "type": "object",
        "properties": {
          "correo": {
            "type": [
              "null",
              "string"
            ]
          },
          "contrasena": {
            "type": [
              "null",
              "string"
            ]
          },
          "codigo2fa": {
            "type": [
              "null",
              "string"
            ]
          },
          "dispositivo": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "RenovarSesionRequest": {
        "required": [
          "tokenRenovacion"
        ],
        "type": "object",
        "properties": {
          "tokenRenovacion": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "TipoUso": {
        "enum": [
          "Verificacion",
          "Auditoria",
          null
        ]
      },
      "VerificarRequest": {
        "required": [
          "uuid",
          "rfcEmisor",
          "rfcReceptor",
          "total"
        ],
        "type": "object",
        "properties": {
          "uuid": {
            "type": [
              "null",
              "string"
            ]
          },
          "rfcEmisor": {
            "type": [
              "null",
              "string"
            ]
          },
          "rfcReceptor": {
            "type": [
              "null",
              "string"
            ]
          },
          "total": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "null",
              "number",
              "string"
            ],
            "format": "double"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Estado"
    },
    {
      "name": "Cuenta"
    },
    {
      "name": "Sesión"
    },
    {
      "name": "Llaves API"
    },
    {
      "name": "Validaciones"
    },
    {
      "name": "Historial"
    },
    {
      "name": "Complementos de pago"
    }
  ]
}