{
    "openapi": "3.0.3",
    "info": {
        "title": "CFDi Nexus API",
        "version": "1.0.0",
        "description": "API REST comercial para consulta del SAT. Backend propio de consultas del SAT con autenticacion por API Key.",
        "contact": {
            "name": "Soporte",
            "url": "https://wa.me/5218712654009",
            "email": "soporte@nexus.cfdi4.com"
        },
        "license": {
            "name": "Propietario (uso comercial privado)"
        }
    },
    "servers": [
        {
            "url": "https://nexus.cfdi4.com",
            "description": "Produccion"
        }
    ],
    "tags": [
        {
            "name": "health",
            "description": "Healthcheck y estado del sistema"
        },
        {
            "name": "api",
            "description": "API REST del proyecto (CFDi Nexus)"
        },
        {
            "name": "consultas",
            "description": "Backend de consultas del SAT (43 endpoints)"
        },
        {
            "name": "webhooks",
            "description": "Webhooks de Stripe y PayPal"
        },
        {
            "name": "auth",
            "description": "Login y autenticacion"
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKey": {
                "type": "apiKey",
                "in": "query",
                "name": "apiclave",
                "description": "API key del cliente. Tambien aceptada en formdata, Bearer header o X-Api-Key header."
            }
        },
        "schemas": {
            "RespuestaExitosa": {
                "type": "object",
                "properties": {
                    "estatus": {
                        "type": "string",
                        "example": "exitoso"
                    },
                    "datos": {
                        "type": "object"
                    },
                    "meta": {
                        "type": "object",
                        "properties": {
                            "identificador_peticion": {
                                "type": "string"
                            },
                            "duracion_ms": {
                                "type": "integer"
                            },
                            "creditos": {
                                "type": "object"
                            }
                        }
                    }
                }
            },
            "RespuestaError": {
                "type": "object",
                "properties": {
                    "estatus": {
                        "type": "string",
                        "example": "error"
                    },
                    "error": {
                        "type": "object",
                        "properties": {
                            "codigo": {
                                "type": "string",
                                "example": "apiclave_invalida"
                            },
                            "mensaje": {
                                "type": "string"
                            }
                        }
                    }
                }
            }
        }
    },
    "paths": {
        "/api/estado": {
            "get": {
                "tags": [
                    "health"
                ],
                "summary": "Healthcheck simple",
                "responses": {
                    "200": {
                        "description": "Servicio operativo"
                    }
                }
            }
        },
        "/api/estado/full": {
            "get": {
                "tags": [
                    "health"
                ],
                "summary": "Healthcheck completo (BD, motor, pasarelas)",
                "responses": {
                    "200": {
                        "description": "Todo OK"
                    },
                    "503": {
                        "description": "Sistema degradado"
                    }
                }
            }
        },
        "/api/creditos/saldo": {
            "post": {
                "tags": [
                    "api"
                ],
                "summary": "Consulta creditos consumidos del mes",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RespuestaExitosa"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key invalida o faltante",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RespuestaError"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/consultar/csf": {
            "post": {
                "tags": [
                    "api"
                ],
                "summary": "Consulta Constancia de Situacion Fiscal",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "rfc"
                                ],
                                "properties": {
                                    "rfc": {
                                        "type": "string",
                                        "pattern": "^[A-Z&Ñ]{3,4}[0-9]{6}[A-Z0-9]{3}$"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "400": {
                        "description": "RFC invalido"
                    },
                    "403": {
                        "description": "RFC distinto al de la API key"
                    },
                    "502": {
                        "description": "Motor no disponible"
                    }
                }
            }
        },
        "/api/cfdi/descargar": {
            "post": {
                "tags": [
                    "api"
                ],
                "summary": "Descarga CFDI (XML o PDF)",
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "uuid"
                                ],
                                "properties": {
                                    "uuid": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "formato": {
                                        "type": "string",
                                        "enum": [
                                            "xml",
                                            "pdf",
                                            "ambos"
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/verificar/sello": {
            "post": {
                "tags": [
                    "api"
                ],
                "summary": "Verifica sello digital de un CFDI",
                "security": [
                    {
                        "ApiKey": []
                    }
                ]
            }
        },
        "/api/cliente": {
            "post": {
                "tags": [
                    "api"
                ],
                "summary": "Estado del cliente en el backend de consultas",
                "security": [
                    {
                        "ApiKey": []
                    }
                ]
            }
        },
        "/api/consultas/{funcion}": {
            "get": {
                "summary": "Proxy universal al backend de consultas del SAT (GET)",
                "tags": [
                    "consultas"
                ]
            },
            "post": {
                "summary": "Proxy universal al backend de consultas del SAT (POST)",
                "tags": [
                    "consultas"
                ]
            },
            "parameters": [
                {
                    "name": "funcion",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/api/webhook/stripe": {
            "post": {
                "tags": [
                    "webhooks"
                ],
                "summary": "Webhook de Stripe (verifica firma)"
            }
        },
        "/api/webhook/paypal": {
            "post": {
                "tags": [
                    "webhooks"
                ],
                "summary": "Webhook de PayPal (verifica firma)"
            }
        }
    }
}